From 2c2d807933c59a2979b29eb8740799638f1668f8 Mon Sep 17 00:00:00 2001
From: Samay Sharma <samay@coredb.io>
Date: Mon, 7 Aug 2023 09:50:00 -0700
Subject: [PATCH] Add build from source instructions (#19)

* Add instructions to install against existing Postgres setup

* Fix link

* Formatting fixes

* More formatting fixes

---------

Co-authored-by: Samay Sharma <samay@tembo.io>
---
 CONTRIBUTING.md | 56 +++++++++++++++++++++++++++++++++++--------------
 README.md       |  4 +++-
 2 files changed, 43 insertions(+), 17 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index c482ea5f..1911c0ca 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,4 +1,4 @@
-# Postgres Message Queue (PGMQ)
+# Contributing to Postgres Message Queue (PGMQ)
 
 ## Installation
 
@@ -8,44 +8,68 @@ The fastest way to get started is by running the Tembo docker image, where PGMQ
 docker run -d --name postgres -e POSTGRES_PASSWORD=postgres -p 5432:5432 quay.io/tembo/pgmq-pg:latest
 ```
 
-# Development
+## Building from source
 
-Setup `pgrx`.
+PGMQ is written as a Rust extension and requires [pgrx](https://github.com/pgcentralfoundation/pgrx).
+
+To build pgmq from source, you need
+* A toolchain capable of building Postgres
+* Rust toolchain
+* [pg_partman](https://github.com/pgpartman/pg_partman).
+
+Once you have those pre-requisites, you need to setup `pgrx`.
 
 ```bash
-cargo install --locked cargo-pgrx
-cargo pgrx init
+cargo install --locked cargo-pgrx --version 0.9.8
 ```
 
-Then, clone this repo and change into this directory.
+Clone the repo and change into the directory.
 
 ```bash
-git clone git@https://github.com/tembo-io/pgmq.git
+git clone https://github.com/tembo-io/pgmq.git
 cd pgmq
 ```
 
-### Setup dependencies
+After this point, the steps differ slightly based on if you'd like to build
+and install against an existing Postgres setup or develop against pgrx managed
+development environment (which installs and allows you to test against multiple
+Postgres versions).
 
-Install:
-- [pg_partman](https://github.com/pgpartman/pg_partman), which is required for partitioned tables.
+### Install to a pre-existing Postgres
 
+Initialize `cargo-pgrx`, and tell it the path to the your `pg_config`. For example,
+if `pg_config` is on your `$PATH` and you have Postgres 15, you can run:
 
-Update postgresql.conf in the development environment.
+```bash
+cargo pgrx init --pg15=`which pg_config`
+```
+Then, to install the release build, you can simply run:
+```
+cargo pgrx install --release
 ```
-#  ~/.pgrx/data-14/postgresql.conf
-shared_preload_libraries = 'pg_partman_bgw'
+
+### Install against pgrx managed Postgres (Recommended for Development)
+
+Initialize `cargo-pgrx` development environment:
+
+```bash
+cargo pgrx init
 ```
 
+**Note**: Make sure you build and install `pg_partman` against the postgres installation
+you want to build against (`PG_CONFIG` in `~/.pgrx/PG_VERSION/pgrx-install/bin/pg_config`
+and `PGDATA` in `/Users/samaysharma/.pgrx/data-PG_MAJOR_VERSION`)
 
-Run the dev environment
+Then, you can use the run command, which will build and install the extension
+and drop you into psql:
 
 ```bash
 cargo pgrx run pg15
 ```
 
-Create the extension
+Finally, you can create the extension and get started with the example in the [README.md](README.md).
 
-```pql
+```psql
 CREATE EXTENSION pgmq cascade;
 ```
 
diff --git a/README.md b/README.md
index a4c693be..b28d8b3e 100644
--- a/README.md
+++ b/README.md
@@ -37,6 +37,8 @@ The fastest way to get started is by running the Tembo docker image, where PGMQ
 docker run -d --name postgres -e POSTGRES_PASSWORD=postgres -p 5432:5432 quay.io/tembo/pgmq-pg:latest
 ```
 
+If you'd like to build from source, you can follow the instructions in [CONTRIBUTING.md](CONTRIBUTING.md)
+
 ## Client Libraries
 
 
@@ -222,7 +224,7 @@ Add the following to `postgresql.conf`. Note, changing `shared_preload_libraries
 `pg_partman_bgw.interval` sets the interval at which `pg_partman` conducts maintenance. This creates new partitions and dropping of partitions falling out of the `retention_interval`. By default, `pg_partman` will keep 4 partitions "ahead" of the currently active partition.
 
 ```
-shared_preload_libraries = 'pg_partman_bgw' # requires restart of Postgrs
+shared_preload_libraries = 'pg_partman_bgw' # requires restart of Postgres
 pg_partman_bgw.interval = 60
 pg_partman_bgw.role = 'postgres'
 pg_partman_bgw.dbname = 'postgres'