Subject: [Pljava-dev] the archive produced by pljava-packaging

From: Chapman Flack <[email-masked]>
Date: Mon, 28 Dec 2015 13:45:20 -0500

Since the move to Maven, an end-product of the build has been an archive
named something like pljava-pgM.N-arch-os-linker(.tar.gz|.zip) where the
.zip format is chosen if building on Windows, .tar.gz anywhere else, and
the archive contents are otherwise the same. The contents are the
important build artifacts, under fixed names: pljava/pljava.so (or .dll,
etc.), pljava/pljava.jar, pljava/examples.jar, ....

As far as what PL/Java 1.5.0 will need for successful execution, the aim
has been to have no hardcoded requirements for where the important files
can go, but rather to have GUC variables that can point to them wherever
they are. That's deliberate because there can be database admins who don't
have root on the server box, or don't otherwise have permission to plant
files in particular standard places, or are setting up unusual installations
(multi-tenant, for example) and have reasons to want different locations
for the PL/Java library, jar, and supporting files. PL/Java itself is
designed to work in any of those situations as long as the GUC variables
are properly set.

All that being said, some well-chosen default locations would simplify
installation in common, uncomplicated, "sudo install something and go"
situations. Looking at existing PG extensions, it seems common to assume
write access to PKGLIBDIR to put the native library there, and to
SHAREDIR/... for other supporting files, particularly SHAREDIR/extension
for .control and .sql files. By choosing default locations and making those
the default values of PL/Java's GUC variables, there could be an
uncomplicated installation without having to set those variables.

The way pljava-packaging currently builds the package archive, you
would still have to extract the few necessary files from it
and manually scatter them out to the 'standard' locations.

Here is a proposal:

1. Build the package archive with directory prefixes based on the
   pg_config keys for standard locations. The contents would be
   something like:

   pljava/PKGLIBDIR/pljava-so-1.5.0.so
   pljava/SHAREDIR/pljava/pljava-1.5.0.jar
   pljava/SHAREDIR/pljava/pljava-examples-1.5.0.jar
   pljava/SHAREDIR/extension/pljava.control
   ...

   The paths are based on pg_config keys (and not what those keys
   expand to on the build system) so the archive can be built once
   and used on other systems where the versions are compatible but
   the filesystem locations might be different.

2. Build the archive in one format always, instead of somewhat
   arbitrarily choosing .zip for Windows and .tar.gz for anything
   else. Rationale: Q. What software component will *all*
   prospective users of PL/Java be sure to have? A. A Java runtime.
   Q. What archive format is always supported by a Java runtime
   even with no other tools present? A. zip (or jar, based on zip).

3. Build the archive to contain extraction code. Again, every
   prospective user has Java, any jar file can have a main class, and
   the class format is platform independent. A simple extractor can
   be written in Java that executes pg_config to find the locations on
   the target system and extracts the archive, rewriting the directory
   keys to the correct locations.

That way, a "standard" installation can be done with just the command:

java -jar pljava-pgM.N-arch-os-linker.jar

while for any other installation it would be treated as an ordinary
zip or jar file and extracted, and the files manually moved to where
they are wanted. (Or, allow the built-in extractor to accept commandline
arguments like PKGLIBDIR=... to override what it would obtain from
pg_config.)

I think this would address issue #6.

Thoughts?

-Chap
_______________________________________________
Pljava-dev mailing list
[email-masked]
http://lists.pgfoundry.org/mailman/listinfo/pljava-dev

---

From: Chapman Flack <[email-masked]>
Date: Mon, 04 Jan 2016 21:09:57 -0500

On 12/28/15 13:45, Chapman Flack wrote:
>    pg_config keys for standard locations. ...
>    The paths are based on pg_config keys ...
> 
> 2. Build the archive in one format always...
>     Rationale: Q. What software component will *all*
>    Q. What archive format is always supported ...A. zip (or jar...
> 

The code that is now pull request #82 at github does the above.
https://github.com/tada/pljava/pull/82

The new docs are in it (mvn site site:stage ; point browser at
target/staging/index.html); an excerpt is below.

-Chap

----------------------------------------------
$h2 For the impatient

After completing the [build][bld]:

    java -jar pljava-packaging/target/pljava-pgX.Y-arch-os-link.jar
    psql
    CREATE EXTENSION pljava;

where *pgX.Y* represents the PostgreSQL version, and *arch*, *os*, and
*link* are ... wait, you're impatient, just look in the directory, you'll
see the jar file there.

*Not running PostgreSQL 9.1 or higher? Use
`LOAD 'libpljava-so-${project.version}';` instead of the `CREATE EXTENSION`
command. (It works in later versions too, if you prefer it to
`CREATE EXTENSION`.) Using a Mac? Be sure to add `.bundle` at the end of the
file name
in the `LOAD` command. Windows? Remove `lib` from the front. Something else?
Keep reading.*

You may get a message that some configuration variable must be set.
If so, keep reading.

$h3 What the above will do

The jar file produced in `pljava-packaging/target` at the end of the build
contains all the files needed to install PL/Java, and it is self-extracting
when simply run with `java -jar`. It does not contain any complicated,
black-box installer, and if you prefer, it is just as easy to extract
normally with the `jar` command or any `zip` tool, in which case you will
see that it contains files at symbolic paths such as

    pljava/pkglibdir/...
    pljava/sharedir/...

which you can move to wherever you like. Those names are based on
the options you would pass to `pg_config` to find
the right locations for your PostgreSQL setup, and that is exactly
what the self-extractor does. Assuming it is run with the permissions needed
to write there, it will put the PL/Java files into the expected locations,
so that `CREATE EXTENSION` will find it without much configuration needed.

Because that is done by the extractor, you can take the built jar file to
other PostgreSQL installations, even with other filesystem layouts, and
it will put the files in the right places there too.

It has to be able to find `pg_config`, and if you have more than one
installation of PostgreSQL on the machine, it has to find the *right*
`pg_config`. You can either arrange the path in your environment so
the right `pg_config` comes first, or specify it with `-Dpgconfig=` on
the command line:

    java -Dpgconfig=/local/pgsql/bin/pg_config -jar pljava-packaging/...

All of the standard install locations can also be changed with `-D`
options:

    java -Dpgconfig.sharedir=/local/foo -jar pljava-packaging/...

would cause all the files that would normally go in the configured
share directory to be placed in `/local/foo` instead. You can therefore
install PL/Java in many situations where you might not have write access
to the standard locations, or might have other reasons to prefer
giving the files another location.
------------------------------------