11/*
2- * Copyright (c) 2020-2021 Tada AB and other contributors, as listed below.
2+ * Copyright (c) 2020-2024 Tada AB and other contributors, as listed below.
33 *
44 * All rights reserved. This program and the accompanying materials
55 * are made available under the terms of the The BSD 3-Clause License
2121import java .util .stream .Collectors ;
2222
2323/**
24- * Class to act as a blueprint for platform specific build configurations in
25- * pljava-so/pom.xml
24+ * Class to act as a blueprint for platform-specific build configurations in a
25+ * {@code pom.xml}.
26+ *<p>
27+ * A {@code scripted-goal} configuration in the POM should contain a script
28+ * that somehow selects and supplies a concrete implementation of this abstract
29+ * class.
30+ *<p>
31+ * In {@code pljava-so/pom.xml}, a block of {@code application/javascript} is
32+ * supplied that contains a {@code configuration} array of JS objects, each of
33+ * which has a {@code name} entry, a {@code probe} function returning true on
34+ * some supported platform, and the necessary functions to serve as an
35+ * implementation of this class. The script selects one whose probe succeeds
36+ * and, using JSR 223 magic, makes an instance of this class from it.
37+ *<p>
38+ * The script can make use of convenience methods implemented here, and also
39+ * a number of items (such as a {@code runCommand} function) presupplied in the
40+ * script engine's binding scope by
41+ * {@link PGXSUtils#getScriptEngine PGXSUtils.getScriptEngine} and by
42+ * {@link ScriptingMojo#execute ScriptingMojo.execute}).
2643 */
2744public abstract class AbstractPGXS
2845{
29-
3046 /**
31- * Add instructions for compiling the pljava-so C files on your platform
32- * by implementing this method in your configuration block.
47+ * Performs platform-specific compilation of a set of {@code .c} files with
48+ * the specified compiler, target path, includes, defines, and flags.
49+ *<p>
50+ * An implementation should make any needed adjustments to the includes,
51+ * defines, and flags, format everything appropriately for the compiler
52+ * in question, execute it, and return an exit status (zero on success).
3353 */
34- public abstract int compile (String compiler , List < String > files , Path targetPath ,
35- List <String > includes , Map < String , String > defines ,
36- List <String > flags );
54+ public abstract int compile (
55+ String compiler , List <String > files , Path targetPath ,
56+ List < String > includes , Map < String , String > defines , List <String > flags );
3757
3858 /**
39- * Add instructions for linking and producing the pljava-so shared library
40- * artifact on your platform by implementing this method in your
41- * configuration block.
59+ * Performs platform-specific linking of a set of object files with
60+ * the specified linker and flags, to produce the shared object at the
61+ * specified target path.
62+ *<p>
63+ * An implementation should make any needed adjustments to the flags, format
64+ * everything appropriately for the linker in question, execute it, and
65+ * return an exit status (zero on success).
4266 */
43- public abstract int link (String linker , List <String > flags , List <String > files , Path targetPath );
67+ public abstract int link (
68+ String linker , List <String > flags , List <String > files , Path targetPath );
4469
4570 /**
4671 * Returns a list with all items prefixed with correct include flag symbol.
4772 *
4873 * This is the default implementation for formatting the list of includes,
49- * and prefixes the includes with -I. For compilers like MSVC that require
50- * different symbols, override this method in your configuration block.
74+ * and prefixes the includes with {@code -I}. For compilers like MSVC that
75+ * require different formatting, the script should supply an overriding
76+ * implementation of this method.
5177 */
5278 public List <String > formatIncludes (List <String > includesList )
5379 {
@@ -56,12 +82,13 @@ public List<String> formatIncludes(List<String> includesList)
5682 }
5783
5884 /**
59- * Returns a list with all defines prefixed correctly.
85+ * Returns a list with all defines represented correctly.
6086 *
61- * This is the default implementation for formatting the list of defines.
62- * Each item is prefixed with -D. If the define is associated with a value,
63- * adds equal symbol also followed by the value. If your linker expects a
64- * different format, override the method in your configuration block.
87+ * This is the default implementation for formatting the map of defines.
88+ * Each item is prefixed with {@code -D}. If the name is mapped to a
89+ * non-null value, an {@code =} is appended, followed by the value. For
90+ * compilers like MSVC that require different formatting, the script should
91+ * supply an overriding implementation of this method.
6592 */
6693 public List <String > formatDefines (Map <String , String > definesMap )
6794 {
@@ -76,11 +103,11 @@ public List<String> formatDefines(Map<String, String> definesMap)
76103 }
77104
78105 /**
79- * Returns the input pg_config property as a list of individual flags split
80- * at whitespace, except when quoted, and the quotes removed.
106+ * Returns the requested {@code pg_config} property as a list of individual
107+ * flags split at whitespace, except when quoted, and the quotes removed.
81108 *<p>
82109 * The assumed quoting convention is single straight quotes around regions
83- * to be protected, which do not have to be the entire argument. This method
110+ * to be protected, which do not have to be an entire argument. This method
84111 * doesn't handle a value that <em>contains</em> a single quote as content;
85112 * the intended convention for that case doesn't seem to be documented, and
86113 * PostgreSQL's own build breaks in such a case, so there is little need,
0 commit comments