INSTALL file
Hello,
while working with Google Code-In students, there is one task: "clone
PostgreSQL from git repository, and build from source".
This brought up an interesting problem: the README refers to an "INSTALL"
file, which is present in packages, but not in the source repo. This is
very confusing for beginners, and should be avoided.
There are a couple options to fix this:
1. Update the README, and remove the "INSTALL" reference
2. Create a permanent INSTALL file, and possibly overwrite it during
packaging
3. Add different INSTALL files, based on the platform (Linux, BSD,
Windows, Source)
Regards,
--
Andreas 'ads' Scherbaum
German PostgreSQL User Group
European PostgreSQL User Group - Board of Directors
Volunteer Regional Contact, Germany - PostgreSQL Project
On 10/28/2018 08:13 AM, Andreas 'ads' Scherbaum wrote:
Hello,
while working with Google Code-In students, there is one task: "clone
PostgreSQL from git repository, and build from source".This brought up an interesting problem: the README refers to an
"INSTALL" file, which is present in packages, but not in the source
repo. This is very confusing for beginners, and should be avoided.There are a couple options to fix this:
1. Update the README, and remove the "INSTALL" reference
2. Create a permanent INSTALL file, and possibly overwrite it during
packaging
3. Add different INSTALL files, based on the platform (Linux, BSD,
Windows, Source)Regards,
See README.git
cheers
andrew
--
Andrew Dunstan https://www.2ndQuadrant.com
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
On 28.10.18 20:39, Andrew Dunstan wrote:
On 10/28/2018 08:13 AM, Andreas 'ads' Scherbaum wrote:
Hello,
while working with Google Code-In students, there is one task: "clone
PostgreSQL from git repository, and build from source".This brought up an interesting problem: the README refers to an
"INSTALL" file, which is present in packages, but not in the source
repo. This is very confusing for beginners, and should be avoided.There are a couple options to fix this:
1. Update the README, and remove the "INSTALL" reference
2. Create a permanent INSTALL file, and possibly overwrite it during
packaging
3. Add different INSTALL files, based on the platform (Linux, BSD,
Windows, Source)Regards,
See README.git
That is not the first file people looking at. Especially not people
looking at the GitHub copy:
https://github.com/postgres/postgres
I understand that there is documentation, but for the casual developer
looking at this, it seems broken.
Regards,
--
Andreas 'ads' Scherbaum
German PostgreSQL User Group
European PostgreSQL User Group - Board of Directors
Volunteer Regional Contact, Germany - PostgreSQL Project
On Mon, Oct 29, 2018 at 01:01:47PM +0100, Andreas 'ads' Scherbaum wrote:
That is not the first file people looking at. Especially not people looking
at the GitHub copy:https://github.com/postgres/postgres
I understand that there is documentation, but for the casual developer
looking at this, it seems broken.
FWIW, I think that people depend too much on github and what github
thinks projects should do to be more presentable, like adding a
markdown-style README or such.
I get your point that people look at README first though, and that the
current status is confusing. One idea would be to merge the contents of
README.git into the README. However the current status also makes some
sense, as INSTALL is part of an distributed tarball, while README.git is
automatically removed when running "make distdir". Looking at README is
the first thing I do when checking out any project or after
decompressing any source code tarball, so things could be better.
--
Michael
That is not the first file people looking at. Especially not people
looking
at the GitHub copy:
https://github.com/postgres/postgres
I understand that there is documentation, but for the casual developer
looking at this, it seems broken.FWIW, I think that people depend too much on github and what github
thinks projects should do to be more presentable, like adding a
markdown-style README or such.
If you push a README.md file formatted in Markdown, github/gitlab will show
it instead of README.
That's the way it is done in PostGIS, showing badges and stuff for github
only:
https://github.com/postgis/postgis
--
Darafei Praliaskouski
Support me: http://patreon.com/komzpa
On 30.10.18 04:11, Michael Paquier wrote:
On Mon, Oct 29, 2018 at 01:01:47PM +0100, Andreas 'ads' Scherbaum wrote:
That is not the first file people looking at. Especially not people looking
at the GitHub copy:https://github.com/postgres/postgres
I understand that there is documentation, but for the casual developer
looking at this, it seems broken.FWIW, I think that people depend too much on github and what github
thinks projects should do to be more presentable, like adding a
markdown-style README or such.I get your point that people look at README first though, and that the
current status is confusing. One idea would be to merge the contents of
README.git into the README. However the current status also makes some
sense, as INSTALL is part of an distributed tarball, while README.git is
automatically removed when running "make distdir". Looking at README is
the first thing I do when checking out any project or after
decompressing any source code tarball, so things could be better.
Right, thanks. That's why one of my proposals was to have an INSTALL
file in place, and overwrite it during the tarball creation process.
This way the general INSTALL file is there, and can contain "general"
instructions, and later on is overwritten by a specific INSTALL file for
the tarballs.
Regards,
--
Andreas 'ads' Scherbaum
German PostgreSQL User Group
European PostgreSQL User Group - Board of Directors
Volunteer Regional Contact, Germany - PostgreSQL Project
On 10/30/2018 06:14 AM, Andreas 'ads' Scherbaum wrote:
On 30.10.18 04:11, Michael Paquier wrote:
On Mon, Oct 29, 2018 at 01:01:47PM +0100, Andreas 'ads' Scherbaum wrote:
That is not the first file people looking at. Especially not people
looking
at the GitHub copy:https://github.com/postgres/postgres
I understand that there is documentation, but for the casual developer
looking at this, it seems broken.FWIW, I think that people depend too much on github and what github
thinks projects should do to be more presentable, like adding a
markdown-style README or such.I get your point that people look at README first though, and that the
current status is confusing.� One idea would be to merge the contents of
README.git into the README.� However the current status also makes some
sense, as INSTALL is part of an distributed tarball, while README.git is
automatically removed when running "make distdir".� Looking at README is
the first thing I do when checking out any project or after
decompressing any source code tarball, so things could be better.Right, thanks. That's why one of my proposals was to have an INSTALL
file in place, and overwrite it during the tarball creation process.This way the general INSTALL file is there, and can contain "general"
instructions, and later on is overwritten by a specific INSTALL file
for the tarballs.
That has the potential to be somewhat confusing:
"The INSTALL file says ..."
"Which INSTALL file are you referring to?"
Merging README.git into README make sense.
I think our attitude has generally been that if you're a developer you
should build from git, in which case we assume you know what you're
doing, and everyone else should build from a tarball. That's arguably
somewhat old-fashioned, specially since you can download release
tarballs/zips from places like
<https://github.com/postgres/postgres/releases> Sadly, these won't have
the artefacts created by "make dist". Maybe those too are less important
these days.
cheers
andrew
--
Andrew Dunstan https://www.2ndQuadrant.com
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
On 30.10.18 11:49, Andrew Dunstan wrote:
On 10/30/2018 06:14 AM, Andreas 'ads' Scherbaum wrote:
On 30.10.18 04:11, Michael Paquier wrote:
On Mon, Oct 29, 2018 at 01:01:47PM +0100, Andreas 'ads' Scherbaum
wrote:That is not the first file people looking at. Especially not people
looking
at the GitHub copy:https://github.com/postgres/postgres
I understand that there is documentation, but for the casual developer
looking at this, it seems broken.FWIW, I think that people depend too much on github and what github
thinks projects should do to be more presentable, like adding a
markdown-style README or such.I get your point that people look at README first though, and that the
current status is confusing. One idea would be to merge the
contents of
README.git into the README. However the current status also makes some
sense, as INSTALL is part of an distributed tarball, while
README.git is
automatically removed when running "make distdir". Looking at
README is
the first thing I do when checking out any project or after
decompressing any source code tarball, so things could be better.Right, thanks. That's why one of my proposals was to have an INSTALL
file in place, and overwrite it during the tarball creation process.This way the general INSTALL file is there, and can contain "general"
instructions, and later on is overwritten by a specific INSTALL file
for the tarballs.That has the potential to be somewhat confusing:
"The INSTALL file says ..."
"Which INSTALL file are you referring to?"
Merging README.git into README make sense.
I think our attitude has generally been that if you're a developer you
should build from git, in which case we assume you know what you're
doing, and everyone else should build from a tarball. That's arguably
somewhat old-fashioned, specially since you can download release
tarballs/zips from places like
<https://github.com/postgres/postgres/releases> Sadly, these won't
have the artefacts created by "make dist". Maybe those too are less
important these days.
Most experienced developers will know, I think. This was raised during
the Google Code-In project, where students stumbled over this, and asked
where the INSTALL file is ...
This has potential to confuse anyone new to PostgreSQL, and it's a
burden which can easily be avoided.
--
Andreas 'ads' Scherbaum
German PostgreSQL User Group
European PostgreSQL User Group - Board of Directors
Volunteer Regional Contact, Germany - PostgreSQL Project
* Andreas 'ads' Scherbaum (ads@pgug.de) wrote:
On 30.10.18 11:49, Andrew Dunstan wrote:
On 10/30/2018 06:14 AM, Andreas 'ads' Scherbaum wrote:
On 30.10.18 04:11, Michael Paquier wrote:
FWIW, I think that people depend too much on github and what github
thinks projects should do to be more presentable, like adding a
markdown-style README or such.
I don't find this to be all that relevant- people clone our git repo all
the time and cloning it either directly or through one of the mirrors is
almost certainly what people interested in working with the source code
will do first, these days.
For better or worse, the days of people pulling down tarballs to start
hacking on code are pretty much gone. We likely still need to provide
the tarballs for our packagers, but that may be gone one day too.
I get your point that people look at README first though, and that the
current status is confusing. One idea would be to merge the contents
of
README.git into the README. However the current status also makes some
sense, as INSTALL is part of an distributed tarball, while README.git
is
automatically removed when running "make distdir". Looking at README
is
the first thing I do when checking out any project or after
decompressing any source code tarball, so things could be better.
The current status is confusing and does *not* make sense today. The
README needs to be updated to be sensible to someone using git to pull
down the repo. The only way to make the current approach make sense
would be to actually *remove* the currently confusing README from the
git repo in its current form and also generate it as part of the tarball
build, but that seems like it's going very much in the wrong direction.
Right, thanks. That's why one of my proposals was to have an INSTALL
file in place, and overwrite it during the tarball creation process.This way the general INSTALL file is there, and can contain "general"
instructions, and later on is overwritten by a specific INSTALL file for
the tarballs.
I'm not really much of a fan of this. My thinking would be to merge the
README.git into the README, and, in particular, provide a very clear
link to the
https://www.postgresql.org/docs/devel/static/installation.html URL. I'd
also be a fan of including the 'Short version' in the README, and/or
maybe instructions on how to build the INSTALL file, but I suspect that
to be non-trivial to someone new.
That has the potential to be somewhat confusing:
"The INSTALL file says ..."
"Which INSTALL file are you referring to?"
Merging README.git into README make sense.
Agreed.
I think our attitude has generally been that if you're a developer you
should build from git, in which case we assume you know what you're doing,
and everyone else should build from a tarball. That's arguably somewhat
old-fashioned, specially since you can download release tarballs/zips from
places like <https://github.com/postgres/postgres/releases> Sadly, these
won't have the artefacts created by "make dist". Maybe those too are less
important these days.
This is more than 'old fashioned', in my view, it's just not what
happens today. Unfortunately, I don't think we have the stats anymore,
but I strongly suspect that our github/git/git mirrors get far more
pulls than our tarballs do now.
Most experienced developers will know, I think. This was raised during the
Google Code-In project, where students stumbled over this, and asked where
the INSTALL file is ...This has potential to confuse anyone new to PostgreSQL, and it's a burden
which can easily be avoided.
Agreed, we should really improve the README by merging the README.git
into it and make the project, as a whole, more accessible to new
developers.
Thanks!
Stephen
On Wed, Oct 31, 2018 at 08:30:40AM -0400, Stephen Frost wrote:
Agreed, we should really improve the README by merging the README.git
into it and make the project, as a whole, more accessible to new
developers.
+1. I think as well that this approach would be a good thing.
--
Michael
Hi,
On 2018-11-01 09:29:37 +0900, Michael Paquier wrote:
On Wed, Oct 31, 2018 at 08:30:40AM -0400, Stephen Frost wrote:
Agreed, we should really improve the README by merging the README.git
into it and make the project, as a whole, more accessible to new
developers.+1. I think as well that this approach would be a good thing.
Strong +1. I was recently looking through the information for new
developers and it's a major mess.
Greetings,
Andres Freund
On 01.11.18 01:29, Michael Paquier wrote:
On Wed, Oct 31, 2018 at 08:30:40AM -0400, Stephen Frost wrote:
Agreed, we should really improve the README by merging the README.git
into it and make the project, as a whole, more accessible to new
developers.+1. I think as well that this approach would be a good thing.
Picking up on this idea, attached is a first draft for changing the README.
It includes links to the website, as well as the short version of the
installation instructions.
Regards,
--
Andreas 'ads' Scherbaum
German PostgreSQL User Group
European PostgreSQL User Group - Board of Directors
Volunteer Regional Contact, Germany - PostgreSQL Project
Attachments:
README.difftext/x-patch; name=README.diffDownload
diff --git a/README b/README
index 12de3f1d73..24814265e8 100644
--- a/README
+++ b/README
@@ -13,14 +13,47 @@ PostgreSQL has many language interfaces, many of which are listed here:
https://www.postgresql.org/download
-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.
+
+Installation
+============
+
+The installation instructions are listed on the website:
+
+https://www.postgresql.org/docs/current/static/install-short.html
+
+Short version:
+
+./configure
+make
+su
+make install
+adduser postgres
+mkdir /usr/local/pgsql/data
+chown postgres /usr/local/pgsql/data
+su - postgres
+/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
+/usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data -l logfile start
+
+The list of supported platforms is available on the website:
+
+https://www.postgresql.org/docs/current/static/supported-platforms.html
+
+Copyright and license information can be found in the file COPYRIGHT.
+
+
+Documentation
+=============
+
+A comprehensive documentation set is included in this distribution;
+it can be read as described in the installation instructions.
+
+The documentation for all versions of PostgreSQL is available on the website:
+
+https://www.postgresql.org/docs/
+
+
+Download
+========
The latest version of this software may be obtained at
https://www.postgresql.org/download/. For more information look at our
On Thu, Nov 01, 2018 at 01:32:09AM +0100, Andreas 'ads' Scherbaum wrote:
Picking up on this idea, attached is a first draft for changing the
README.
Why don't you add it to the upcoming commit fest? It would be good to
get some traction with a formal review.
It includes links to the website, as well as the short version of the
installation instructions.
+The installation instructions are listed on the website:
+
+https://www.postgresql.org/docs/current/static/install-short.html
+
+Short version:
+
+./configure
+make
+su
+make install
+adduser postgres
+mkdir /usr/local/pgsql/data
+chown postgres /usr/local/pgsql/data
+su - postgres
+/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
+/usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data -l logfile startAdding a section about installation and another one about documentation
are good things. Now for the installation section I disagree about
adding this detailed way of doing things, and just adding a URL looks
enough.
Pointing to the global installation recommendations would be a better
fit also as a lot of things are platform-dependent. So this URL looks
better:
https://www.postgresql.org/docs/current/static/installation.html
Now there is also a problem, the README would point out to the
development version of the documentation. As this is made at working
using git, I could personally live with having stable branches also
refer to the development version, but it could also make sense to have
each stable branch point to the URL of the versions they work on.
--
Michael
On 01.11.18 07:26, Michael Paquier wrote:
On Thu, Nov 01, 2018 at 01:32:09AM +0100, Andreas 'ads' Scherbaum wrote:
Picking up on this idea, attached is a first draft for changing the
README.Why don't you add it to the upcoming commit fest? It would be good to
get some traction with a formal review.
I plan to do that, once I gathered some feedback here.
It includes links to the website, as well as the short version of the
installation instructions.+The installation instructions are listed on the website: + +https://www.postgresql.org/docs/current/static/install-short.html + +Short version: + +./configure +make +su +make install +adduser postgres +mkdir /usr/local/pgsql/data +chown postgres /usr/local/pgsql/data +su - postgres +/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data +/usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data -l logfile startAdding a section about installation and another one about documentation
are good things. Now for the installation section I disagree about
adding this detailed way of doing things, and just adding a URL looks
enough.
Was thinking about this, but then decided to add it as an example,
and see what people think.
Pointing to the global installation recommendations would be a better
fit also as a lot of things are platform-dependent. So this URL looks
better:
https://www.postgresql.org/docs/current/static/installation.htmlNow there is also a problem, the README would point out to the
development version of the documentation. As this is made at working
using git, I could personally live with having stable branches also
refer to the development version, but it could also make sense to have
each stable branch point to the URL of the versions they work on.
That is a bit problematic. The README lives on git first, and therefore
should point to the development version. The release process
can replace this with links to the current version.
Regards,
--
Andreas 'ads' Scherbaum
German PostgreSQL User Group
European PostgreSQL User Group - Board of Directors
Volunteer Regional Contact, Germany - PostgreSQL Project
Greetings,
* Andreas 'ads' Scherbaum (ads@pgug.de) wrote:
On 01.11.18 07:26, Michael Paquier wrote:
It includes links to the website, as well as the short version of the
installation instructions.+The installation instructions are listed on the website: + +https://www.postgresql.org/docs/current/static/install-short.html
I don't think we should link to the "Short version" directly here, the
above URL should be the "installation.html" one.. With a caveat, see
below.
+Short version: + +./configure +make +su +make install +adduser postgres +mkdir /usr/local/pgsql/data +chown postgres /usr/local/pgsql/data +su - postgres +/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data +/usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data -l logfile startAdding a section about installation and another one about documentation
are good things. Now for the installation section I disagree about
adding this detailed way of doing things, and just adding a URL looks
enough.Was thinking about this, but then decided to add it as an example,
and see what people think.
I like having the detail, but I'd go farther, really. Here's my
thinking:
BUILDING ON UNIX
====================
Detailed instructions for many Unix platforms is available here:
https://www.postgresql.org/docs/current/static/installation.html
To build PostgreSQL on most Unix variants, the following are required:
GNU make, version 3.8 or newer
ISO/ANSI C compilar (at least C99-compliant)
Flex 2.5.31 or later, and Bison 1.875 or later (for building from git)
Perl 5.8.3 (for building from git)
PostgreSQL has many additional capabilities which can be enabled using
configure --enable switches but many of those also depend on additional
libraries. See the installation instructions for details.
To build PostgreSQL, run the following commands:
./configure
make
PostgreSQL can then be installed using 'make install', which will
require being a superuser to install into the default directory.
The installation location can be changed by passing '--prefix' to
'configure'. Run './configure --help' for additional options.
BUILDING ON WINDOWS
====================
Detailed instructions for building on Windows is available here:
https://www.postgresql.org/docs/current/static/install-windows.html
To build PostgreSQL on Windows, either Visual Studio Express 2017
for Windows Desktop or Microsoft Visual C++ 2005 (or later) should be
installed. PostgreSQL can also be build using MinGW or Cygwin using
the Unix instructions.
... some details about how to actually use VSE 2017 would be good
CREATING YOUR FIRST DATABASE
============================
Once the PostgreSQL software is installed, the first step to having a
running database is to initialize a PostgreSQL database using the
'initdb' command, eg:
initdb -D mydatabase
After the database system has been initialized, PostgreSQL can be
started by using the pg_ctl command:
pg_ctl -D mydatabase -l logfile start
Once PostgreSQL is running, you can connect to it using the psql
command-line client. A default database called 'postgres' was created
by 'initdb'.
BUILDING THE POSTGRESQL DOCUMENTATION
=====================================
Full documentation for PostgreSQL is available online here:
https://www.postgresql.org/docs/current/static/index.html
To build the PostgreSQL documentation on most Unix variants, the
following tools are required:
.... whatever these are
To build PostgreSQL's documentation on Unix, run:
./configure
make docs
The documentation, once built by 'make docs', will be available in
various formats in the 'doc/src/sgml' directory.
Now there is also a problem, the README would point out to the
development version of the documentation. As this is made at working
using git, I could personally live with having stable branches also
refer to the development version, but it could also make sense to have
each stable branch point to the URL of the versions they work on.That is a bit problematic. The README lives on git first, and therefore
should point to the development version. The release process
can replace this with links to the current version.
I'm not sure that I'm really following this, because we aren't pointing
to the development documentation, just the 'current' documentation, and
that seems fine, and there's links on that page to the other versions of
the page for each major version of PostgreSQL, in case someone pulled an
older branch or such.
In short, I think we're fine to just use the 'current' URLs in this
README.
I'd also update the 'Makefile' bit we have at the root to refer to the
README instead of the INSTALL file.
Thanks!
Stephen
On 01.11.18 18:41, Stephen Frost wrote:
Greetings,
* Andreas 'ads' Scherbaum (ads@pgug.de) wrote:
On 01.11.18 07:26, Michael Paquier wrote:
It includes links to the website, as well as the short version of the
installation instructions.+The installation instructions are listed on the website: + +https://www.postgresql.org/docs/current/static/install-short.htmlI don't think we should link to the "Short version" directly here, the
above URL should be the "installation.html" one.. With a caveat, see
below.
How about the attached one? Picked up your draft, and cleaned it up a bit.
--
Andreas 'ads' Scherbaum
German PostgreSQL User Group
European PostgreSQL User Group - Board of Directors
Volunteer Regional Contact, Germany - PostgreSQL Project
Attachments:
README.difftext/x-patch; name=README.diffDownload
diff --git a/README b/README
index 12de3f1d73..1f33303d80 100644
--- a/README
+++ b/README
@@ -13,14 +13,94 @@ PostgreSQL has many language interfaces, many of which are listed here:
https://www.postgresql.org/download
-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.
+
+Building on UNIX
+================
+
+Detailed instructions for many Unix platforms are available here:
+https://www.postgresql.org/docs/current/static/installation.html
+
+To build PostgreSQL on most Unix variants, the following are required:
+
+GNU make, version 3.8 or newer
+ISO/ANSI C compilar (at least C99-compliant)
+Flex 2.5.31 or later, and Bison 1.875 or later (for building from git)
+Perl 5.8.3 (for building from git)
+
+PostgreSQL has many additional capabilities which can be enabled using
+configure --enable switches but many of those also depend on additional
+libraries. See the installation instructions for details.
+
+To build PostgreSQL, run the following commands:
+
+./configure
+make
+
+PostgreSQL can then be installed using 'make install', which will
+require being a superuser to install into the default directory.
+The installation location can be changed by passing '--prefix' to
+'configure'. Run './configure --help' for additional options.
+
+
+Building on Windows
+===================
+
+Detailed instructions for building on Windows is available here:
+https://www.postgresql.org/docs/current/static/install-windows.html
+
+To build PostgreSQL on Windows, either Visual Studio Express 2017
+for Windows Desktop or Microsoft Visual C++ 2005 (or later) should be
+installed. PostgreSQL can also be build using MinGW or Cygwin using
+the Unix instructions.
+
+There are different requirements for building on a 32-bit or 64-bit
+environment, check the documentation for details.
+
+
+Initializing your Database
+==========================
+
+Once the PostgreSQL software is installed, the first step to having a
+running database is to initialize a PostgreSQL database using the
+'initdb' command, eg:
+
+initdb -D /path/to/mydatabase
+
+Where '/path/to/mydatabase' is the directory where the database is
+going to be installed. This directory can exist, but must be empty.
+If it does not exist, 'initdb' will create it.
+
+After the database system has been initialized, PostgreSQL can be
+started by using the pg_ctl command:
+
+pg_ctl -D /path/to/mydatabase -l logfile start
+
+Once PostgreSQL is running, you can connect to it using the psql
+command-line client. A default database called 'postgres' was created
+by 'initdb'.
+
+
+Building the PostgreSQL Documentation
+=====================================
+
+Full documentation for PostgreSQL is available online here:
+https://www.postgresql.org/docs/current/static/index.html
+
+PostgreSQL uses DocBook to build the documentation. Therefore the
+DocBook tools must be installed. In addition, a working Java
+installation is required.
+
+To build PostgreSQL's documentation on Unix, run:
+
+./configure
+make docs
+
+The documentation, once built by 'make docs', will be available in
+various formats in the 'doc/src/sgml' directory.
+
+
+Download
+========
The latest version of this software may be obtained at
https://www.postgresql.org/download/. For more information look at our
On Thu, Nov 01, 2018 at 01:41:33PM -0400, Stephen Frost wrote:
I'm not sure that I'm really following this, because we aren't pointing
to the development documentation, just the 'current' documentation, and
that seems fine, and there's links on that page to the other versions of
the page for each major version of PostgreSQL, in case someone pulled an
older branch or such.
Imagine for example that Postgres switches from ./configure to cmake,
this makes the current version of the documentation invalid on
back-branches, still they refer to it. If we target that stuff for
beginners, they may just look into those docs, without thinking that
they actually need the version of the docs with the branch checked out.
My 2c.
--
Michael
Greetings,
* Andreas 'ads' Scherbaum (ads@pgug.de) wrote:
How about the attached one? Picked up your draft, and cleaned it up a bit.
(unsurprisingly) this is looking pretty good to me.
A few additional notes:
PostgreSQL Database Management System
=====================================This directory contains the source code distribution of the PostgreSQL
database management system.PostgreSQL is an advanced object-relational database management system
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.PostgreSQL has many language interfaces, many of which are listed here:
Honestly, I don't think the above link makes sense when we're saying
"here's where to go to download language interfaces." We could maybe
link to https://www.postgresql.org/download/products/2-drivers-and-interfaces/
instead, but that link is really pretty messy, imv.
Instead, I'd just move the 'Download' section that's at the end up to
here.
Building on Windows
===================Detailed instructions for building on Windows is available here:
https://www.postgresql.org/docs/current/static/install-windows.htmlTo build PostgreSQL on Windows, either Visual Studio Express 2017
for Windows Desktop or Microsoft Visual C++ 2005 (or later) should be
installed. PostgreSQL can also be build using MinGW or Cygwin using
the Unix instructions.
The above should say "can also be built", not "build".
Initializing your Database
==========================Once the PostgreSQL software is installed, the first step to having a
running database is to initialize a PostgreSQL database using the
'initdb' command, eg:initdb -D /path/to/mydatabase
We probably shouldn't say 'eg' but should use language similar to what
we say above, which would be "run this command" or so.
Where '/path/to/mydatabase' is the directory where the database is
going to be installed. This directory can exist, but must be empty.
If it does not exist, 'initdb' will create it.After the database system has been initialized, PostgreSQL can be
started by using the pg_ctl command:pg_ctl -D /path/to/mydatabase -l logfile start
Once PostgreSQL is running, you can connect to it using the psql
command-line client. A default database called 'postgres' was created
by 'initdb'.
I didn't include a full path intentionally, simply because paths look
different between Unix systems and Windows. That said, I don't think
it's a big deal either way.
Building the PostgreSQL Documentation
=====================================
I've been going back and forth on this, but it seems like building the
documentation should maybe be above the Initializing a database..? I
could go either way on it.
Download
========The latest version of this software may be obtained at
https://www.postgresql.org/download/. For more information look at our
web site located at https://www.postgresql.org/.
I'd suggest we change this to be something like:
The latest version of this software, both in source code form and as
binary packages for many platforms, may be obtained at
https://www.postgresql.org/download/. For more information please visit
https://www.postgresql.org/.
Thanks!
Stephen
Greetings,
* Michael Paquier (michael@paquier.xyz) wrote:
On Thu, Nov 01, 2018 at 01:41:33PM -0400, Stephen Frost wrote:
I'm not sure that I'm really following this, because we aren't pointing
to the development documentation, just the 'current' documentation, and
that seems fine, and there's links on that page to the other versions of
the page for each major version of PostgreSQL, in case someone pulled an
older branch or such.Imagine for example that Postgres switches from ./configure to cmake,
this makes the current version of the documentation invalid on
back-branches, still they refer to it. If we target that stuff for
beginners, they may just look into those docs, without thinking that
they actually need the version of the docs with the branch checked out.
I'd say we're targeting beginner developers, not beginner computer
users.
That said, I suppose it wouldn't be all that hard to have a different
version of the README for each branch and to keep it updated as we make
releases.
One point I'll make though is that we do need to have the README checked
into git, since that's where most people are getting the source.
If we go down this route, the master branch should probably link to the
regularly built devel documentation, so that if/when we do make such a
change, we'll point people at the updated documentation too.
Thanks!
Stephen
On Thu, Nov 01, 2018 at 08:42:34PM -0400, Stephen Frost wrote:
If we go down this route, the master branch should probably link to the
regularly built devel documentation, so that if/when we do make such a
change, we'll point people at the updated documentation too.
I don't know how others feel about such things, so I may be
overengineering a simple problem as well :)
Also, I have not looked in details at the perl tools used to change the
version number in the tree, but we'd likely want a solution which
updates automatically the README also in this case depending on the
version number, perhaps also making sure that for a git repository with
the master branch in use we don't want to point to the development
version of the docs.
--
Michael
Greetings,
* Michael Paquier (michael@paquier.xyz) wrote:
On Thu, Nov 01, 2018 at 08:42:34PM -0400, Stephen Frost wrote:
If we go down this route, the master branch should probably link to the
regularly built devel documentation, so that if/when we do make such a
change, we'll point people at the updated documentation too.I don't know how others feel about such things, so I may be
overengineering a simple problem as well :)Also, I have not looked in details at the perl tools used to change the
version number in the tree, but we'd likely want a solution which
updates automatically the README also in this case depending on the
version number, perhaps also making sure that for a git repository with
the master branch in use we don't want to point to the development
version of the docs.
Updating version_stamp.pl should be pretty straight-forward to have it
also update the README for the back-branches and it shouldn't be hard to
teach it how to ignore the README on the master branch.
As for what's in the README on the master branch, I was saying that it
*should* point to the development documentation, since that should be
current with whatever is actually in the git repo (or only a day behind
or such).
Thanks!
Stephen
On 02.11.18 01:38, Stephen Frost wrote:
Greetings,
* Andreas 'ads' Scherbaum (ads@pgug.de) wrote:
How about the attached one? Picked up your draft, and cleaned it up a bit.
(unsurprisingly) this is looking pretty good to me.
A few additional notes:
Incorporated. See the attached.
If that works for you, I will submit it to the Commitfest.
Regards,
--
Andreas 'ads' Scherbaum
German PostgreSQL User Group
European PostgreSQL User Group - Board of Directors
Volunteer Regional Contact, Germany - PostgreSQL Project
Attachments:
README.difftext/x-patch; name=README.diffDownload
diff --git a/README b/README
index 12de3f1d73..09ac40fa1c 100644
--- a/README
+++ b/README
@@ -9,19 +9,107 @@ 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.
+
+
+Download
+========
+
+The latest version of this software, both in source code form and as
+binary packages for many platforms, may be obtained at
+
+ https://www.postgresql.org/download/
+
PostgreSQL has many language interfaces, many of which are listed here:
- https://www.postgresql.org/download
+ https://www.postgresql.org/download/products/2-drivers-and-interfaces/
+
+For more information please visit
+
+ https://www.postgresql.org/.
+
+
+Building on UNIX
+================
+
+Detailed instructions for many Unix platforms are available here:
+https://www.postgresql.org/docs/current/static/installation.html
+
+To build PostgreSQL on most Unix variants, the following are required:
+
+GNU make, version 3.8 or newer
+ISO/ANSI C compilar (at least C99-compliant)
+Flex 2.5.31 or later, and Bison 1.875 or later (for building from git)
+Perl 5.8.3 (for building from git)
+
+PostgreSQL has many additional capabilities which can be enabled using
+configure --enable switches but many of those also depend on additional
+libraries. See the installation instructions for details.
+
+To build PostgreSQL, run the following commands:
+
+./configure
+make
+
+PostgreSQL can then be installed using 'make install', which will
+require being a superuser to install into the default directory.
+The installation location can be changed by passing '--prefix' to
+'configure'. Run './configure --help' for additional options.
+
+
+Building on Windows
+===================
+
+Detailed instructions for building on Windows is available here:
+
+ https://www.postgresql.org/docs/current/static/install-windows.html
+
+To build PostgreSQL on Windows, either Visual Studio Express 2017
+for Windows Desktop or Microsoft Visual C++ 2005 (or later) should be
+installed. PostgreSQL can also be built using MinGW or Cygwin using
+the Unix instructions.
+
+There are different requirements for building on a 32-bit or 64-bit
+environment, check the documentation for details.
+
+
+Initializing your Database
+==========================
+
+Once the PostgreSQL software is installed, the first step to having a
+running database is to initialize a PostgreSQL database, using the
+'initdb' command:
+
+initdb -D /path/to/mydatabase
+
+Where '/path/to/mydatabase' is the directory where the database is
+going to be installed. This directory can exist, but must be empty.
+If it does not exist, 'initdb' will create it.
+
+After the database system has been initialized, PostgreSQL can be
+started by using the pg_ctl command:
+
+pg_ctl -D /path/to/mydatabase -l logfile start
+
+Once PostgreSQL is running, you can connect to it using the psql
+command-line client. A default database called 'postgres' was created
+by 'initdb'.
+
+
+Building the PostgreSQL Documentation
+=====================================
+
+Full documentation for PostgreSQL is available online here:
+
+ https://www.postgresql.org/docs/current/static/index.html
+
+PostgreSQL uses DocBook to build the documentation. Therefore the
+DocBook tools must be installed. In addition, a working Java
+installation is required.
+
+To build PostgreSQL's documentation on Unix, run:
-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.
+./configure
+make docs
-The latest version of this software may be obtained at
-https://www.postgresql.org/download/. For more information look at our
-web site located at https://www.postgresql.org/.
+The documentation, once built by 'make docs', will be available in
+various formats in the 'doc/src/sgml' directory.
On Fri, Nov 02, 2018 at 06:47:19AM -0400, Stephen Frost wrote:
As for what's in the README on the master branch, I was saying that it
*should* point to the development documentation, since that should be
current with whatever is actually in the git repo (or only a day behind
or such).
Definitely!
--
Michael
Greetings,
* Andreas 'ads' Scherbaum (ads@pgug.de) wrote:
On 02.11.18 01:38, Stephen Frost wrote:
* Andreas 'ads' Scherbaum (ads@pgug.de) wrote:
How about the attached one? Picked up your draft, and cleaned it up a bit.
(unsurprisingly) this is looking pretty good to me.
A few additional notes:
Incorporated. See the attached.
If that works for you, I will submit it to the Commitfest.
Yeah, looks pretty good to me, please register it in the CF system.
Thanks!
Stephen
On 03.11.18 18:06, Stephen Frost wrote:
Greetings,
* Andreas 'ads' Scherbaum (ads@pgug.de) wrote:
On 02.11.18 01:38, Stephen Frost wrote:
* Andreas 'ads' Scherbaum (ads@pgug.de) wrote:
How about the attached one? Picked up your draft, and cleaned it up a bit.
(unsurprisingly) this is looking pretty good to me.
A few additional notes:
Incorporated. See the attached.
If that works for you, I will submit it to the Commitfest.
Yeah, looks pretty good to me, please register it in the CF system.
Done. Added you for review.
--
Andreas 'ads' Scherbaum
German PostgreSQL User Group
European PostgreSQL User Group - Board of Directors
Volunteer Regional Contact, Germany - PostgreSQL Project
On 03/11/2018 00:14, Andreas 'ads' Scherbaum wrote:
GNU make, version 3.8 or newer
ISO/ANSI C compilar (at least C99-compliant)
Flex 2.5.31 or later, and Bison 1.875 or later (for building from git)
Perl 5.8.3 (for building from git)
I'm not in favor of listing all these versions here. It's one more
thing to keep updated. The version requirements are not outrageous, so
we can assume that someone with a reasonably up-to-date development
machine has appropriate versions.
I'm also not convinced that this list is actually complete. From an
"empty" start you'd typically need at least zlib and readline on top of
those.
--
Peter Eisentraut http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
On Mon, Jan 28, 2019 at 10:21:03PM +0100, Peter Eisentraut wrote:
I'm not in favor of listing all these versions here. It's one more
thing to keep updated. The version requirements are not outrageous, so
we can assume that someone with a reasonably up-to-date development
machine has appropriate versions.
+1. I have just looked at the patch, and my take is that listing all
the ways to build Postgres directly in the README is just a
duplication of what we already have in the documentation. So I would
just rip out all that and keep a simple link to the documentation.
I'm also not convinced that this list is actually complete. From an
"empty" start you'd typically need at least zlib and readline on top of
those.
Yep.
For now I have moved the patch to next CF, waiting on author.
--
Michael
Hi,
On 2019-02-04 11:02:44 +0900, Michael Paquier wrote:
+1. I have just looked at the patch, and my take is that listing all
the ways to build Postgres directly in the README is just a
duplication of what we already have in the documentation. So I would
just rip out all that and keep a simple link to the documentation.
Well, the documentation cannot be built without the dependencies, and
not everyone has convenient internet access. I'm not sure what the
solution to that is, but somehow consolidating that information in the,
by now pretty standardized, location of INSTALL seems pretty reasonable
to me.
Greetings,
Andres Freund
On 14/02/2019 20:13, Andres Freund wrote:
On 2019-02-04 11:02:44 +0900, Michael Paquier wrote:
+1. I have just looked at the patch, and my take is that listing all
the ways to build Postgres directly in the README is just a
duplication of what we already have in the documentation. So I would
just rip out all that and keep a simple link to the documentation.Well, the documentation cannot be built without the dependencies, and
not everyone has convenient internet access. I'm not sure what the
solution to that is, but somehow consolidating that information in the,
by now pretty standardized, location of INSTALL seems pretty reasonable
to me.
(I suppose you meant README here. The information is already in INSTALL.)
But the proposed additions don't actually mention the required
dependencies to build the documentation, so it wouldn't even achieve
that goal.
And if you don't have internet access, how did you get the git checkout?
The use case here seems pretty narrow.
--
Peter Eisentraut http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Hi Andreas,
On 2/15/19 11:59 AM, Peter Eisentraut wrote:
On 14/02/2019 20:13, Andres Freund wrote:
On 2019-02-04 11:02:44 +0900, Michael Paquier wrote:
+1. I have just looked at the patch, and my take is that listing all
the ways to build Postgres directly in the README is just a
duplication of what we already have in the documentation. So I would
just rip out all that and keep a simple link to the documentation.Well, the documentation cannot be built without the dependencies, and
not everyone has convenient internet access. I'm not sure what the
solution to that is, but somehow consolidating that information in the,
by now pretty standardized, location of INSTALL seems pretty reasonable
to me.(I suppose you meant README here. The information is already in INSTALL.)
But the proposed additions don't actually mention the required
dependencies to build the documentation, so it wouldn't even achieve
that goal.And if you don't have internet access, how did you get the git checkout?
The use case here seems pretty narrow.
Any thoughts on Peter and Andres' comments?
Regards,
--
-David
david@pgmasters.net
Hi,
On 2019-03-21 22:06:36 +0400, David Steele wrote:
On 2/15/19 11:59 AM, Peter Eisentraut wrote:
On 14/02/2019 20:13, Andres Freund wrote:
On 2019-02-04 11:02:44 +0900, Michael Paquier wrote:
+1. I have just looked at the patch, and my take is that listing all
the ways to build Postgres directly in the README is just a
duplication of what we already have in the documentation. So I would
just rip out all that and keep a simple link to the documentation.Well, the documentation cannot be built without the dependencies, and
not everyone has convenient internet access. I'm not sure what the
solution to that is, but somehow consolidating that information in the,
by now pretty standardized, location of INSTALL seems pretty reasonable
to me.(I suppose you meant README here. The information is already in INSTALL.)
But the proposed additions don't actually mention the required
dependencies to build the documentation, so it wouldn't even achieve
that goal.And if you don't have internet access, how did you get the git checkout?
The use case here seems pretty narrow.
Any thoughts on Peter and Andres' comments?
Given nothing happened since then I think we ought to mark this as
returned with feedback? Will do so tomorrow.
Greetings,
Andres Freund