From fe7e3947f11d82cfdc1dec8e9cad03cfa9a3c2b8 Mon Sep 17 00:00:00 2001
From: Daniele Varrazzo <daniele.varrazzo@gmail.com>
Date: Mon, 23 Nov 2020 05:23:48 +0000
Subject: [PATCH] Added installation instructions including the binary package

---
 docs/install.rst      | 75 ++++++++++++++++++++++++++++++++++++++++---
 psycopg3_c/README.rst | 24 ++++++++++++++
 2 files changed, 95 insertions(+), 4 deletions(-)

diff --git a/docs/install.rst b/docs/install.rst
index 13019ee9d..85202f29d 100644
--- a/docs/install.rst
+++ b/docs/install.rst
@@ -3,9 +3,76 @@
 Installation
 ============
 
-`!psycopg3` is still in a development phase, and hasn't been released yet.
+.. warning::
 
-Please refer to `the README`__ for the current installation state, and please know
-that things may change.
+    `!psycopg3` is still in a development phase: packages haven't been
+    released yet on PyPI.
 
-.. __: https://github.com/psycopg/psycopg3#readme
+    Please refer to `the README`__ for the current installation state, and
+    please know that things may change.
+
+    .. __: https://github.com/psycopg/psycopg3#readme
+
+    The following is how it will be *supposed* to work, once it is released...
+
+
+Quick install
+-------------
+
+The quickest way to start developing with psycopg3 is to run::
+
+    pip install psycopg3[binary]
+
+This will install a self-contained package with all the libraries needed.
+
+The above package should work in most situations. It **will not work** in
+some though:
+
+- the ``binary`` package doesn't work on Alpine Linux;
+- the ``binary`` package is not advised in production.
+
+
+Proper installation
+-------------------
+
+Proper install means obtaining a performing and maintainable library. The
+library will include a performing C module and will be bound to the system
+libpq, so that system upgrade of libraries will upgrade the library used by
+``psycopg3``.
+
+In order to perform a "proper" installation you need some prerequisites:
+
+- a C compiler,
+- Python development headers (e.g. the python3-dev package).
+- PostgreSQL client development headers (e.g. the libpq-dev package).
+- The :program:`pg_config` program available in the :envvar:`PATH`.
+
+You **must be able** to troubleshoot an extension build, for instance you must
+be able to read your compiler's error message. If you are not, please don't
+try this and follow the `quick install`_ instead.
+
+If your build prerequisites are in place you can run::
+
+    pip install psycopg3[c]
+
+
+Pure Python installation
+------------------------
+
+If you simply install::
+
+    pip install psycopg3
+
+without ``[c]`` or ``[binary]`` extras you will obtain a pure Python
+implementation. This is particularly handy to debug and hack, but it still
+requires the system libpq to operate (which will be used dynamically via
+`ctypes`).
+
+In order to use the pure Python installation you will need the ``libpq``
+installed in the system: for instance on Debian system you will probably
+need::
+
+    sudo apt-get install libpq5
+
+If you are not able to fulfill this requirement please follow the `quick
+install`_.
diff --git a/psycopg3_c/README.rst b/psycopg3_c/README.rst
index 42a87ae0a..3cf7adb2a 100644
--- a/psycopg3_c/README.rst
+++ b/psycopg3_c/README.rst
@@ -16,4 +16,28 @@ Please read `the project readme`__ for more details.
 
 .. __: https://github.com/psycopg/psycopg3#readme
 
+
+Requirements
+------------
+
+On Linux, in order to install this package you will need:
+
+- a C compiler,
+- the libpq development packages (packages libpq-dev or postgresql-devel,
+  according to your distribution)
+- the `pg_config` binary in your PATH
+
+If you don't have these prerequisites please don't try to install this
+package: please install the `binary version`_.
+
+
+Binary version
+--------------
+
+This library is available pre-compiled and bundled with all the required
+client library as ``psycopg3_binary``. In order to use it please install::
+
+    pip install psycopg3[binary]
+
+
 Copyright (C) 2020 The Psycopg Team
-- 
2.47.2