Merge pull request #85 from cps-org/require-prefix

Require "prefix", allow absolute prefixes

conf.py

@@ -13,7 +13,7 @@
 project = 'Common Package Specification'
 copyright = '2024, Matthew Woehlke'
 
-version_info = (0, 12, 0)
+version_info = (0, 13, 0)
 release = '.'.join(map(str, version_info))
 version = '.'.join(map(str, version_info[:2]))
 

overview.rst

@@ -84,7 +84,7 @@ Advantages of CPS
 **Relocatable Installs**
 
   CPS allows and encourages packages to specify locations
-  relative to the package's install prefix,
+  relative to the package's installation prefix,
   which allows the user to choose where to install a pre-built package
   with no need to modify the installed files,
   or even to move an already-installed package to a different location.

schema.rst

@@ -212,11 +212,13 @@ Attribute names are case sensitive.
 
   Specifies the directory portion location of the ``.cps`` file.
   This shall be an "absolute" path which starts with ``@prefix@``.
-  This provides an additional mechanism
-  by which the tool may deduce the package's prefix,
-  since the absolute location of the ``.cps`` file
-  will be known by the tool.
-  (See also `Prefix Determination`_.)
+  This provides a mechanism by which the tool
+  may deduce the prefix of a relocatable package
+  from the absolute location of the ``.cps`` file
+  (which will be known by the tool).
+  See also `Prefix Determination`_ for details.
+
+  Exactly **one** of ``cps_path`` or `prefix`_ is required.
 
 .. ----------------------------------------------------------------------------
 .. cps:attribute:: cps_version
@@ -301,7 +303,7 @@ Attribute names are case sensitive.
   which should be added to the include search path
   when compiling code that consumes the component.
   If a path starts with ``@prefix@``,
-  the package's install prefix is substituted
+  the package's prefix is substituted
   (see `Package Searching`_).
   This is recommended, as it allows packages to be relocatable.
 
@@ -418,7 +420,7 @@ Attribute names are case sensitive.
   while `location`_ shall give the location of the ``.dll``.
 
   If the path starts with ``@prefix@``,
-  the package's install prefix is substituted
+  the package's prefix is substituted
   (see `Package Searching`_).
   This is recommended, as it allows packages to be relocatable.
 
@@ -452,7 +454,7 @@ Attribute names are case sensitive.
   See also `link_location`_.)
 
   If the path starts with ``@prefix@``,
-  the package's install prefix is substituted
+  the package's prefix is substituted
   (see `Package Searching`_).
   This is recommended, as it allows packages to be relocatable.
 
@@ -494,6 +496,17 @@ Attribute names are case sensitive.
   so packages consisting entirely of Java and/or CLR components
   will still typically use this attribute.)
 
+.. ----------------------------------------------------------------------------
+.. cps:attribute:: prefix
+  :type: string
+  :context: package
+
+  Specifies the package's prefix
+  for non-relocatable package.
+  See also `Prefix Determination`_.
+
+  Exactly **one** of `cps_path`_ or ``prefix`` is required.
+
 .. ----------------------------------------------------------------------------
 .. cps:attribute:: requires
   :type: list(string)

searching.rst

@@ -119,50 +119,41 @@ and the reason for rejection.)
 Prefix Determination
 ''''''''''''''''''''
 
-In order to determine the package prefix,
-which may appear in various attributes as ``@prefix@``,
-it is necessary to determine the effective prefix
-from the canonical location of the ``.cps`` file.
-This can be accomplished in three ways:
-
-- If the package specifies a :attribute:`cps_path`,
-  that value shall be used.
-
-- Otherwise, if the tool has just completed a search
-  for the ``.cps``, as described above,
-  the prefix is known from the path which was searched.
-
-- Otherwise, the prefix shall be deduced as follows:
-
-  - The path is initially taken to be the directory portion
-    (i.e. without file name) of the absolute path to the ``.cps`` file.
-
-  - :applies-to:`(macOS)`
-    If the tail-portion matches
-    :path:`/Resources/` or :path:`/Resources/CPS/`,
-    then:
-
-    - The matching portion is removed.
-
-    - If the tail-portion of the remaining path
-      matches :path:`/Versions/`\ :glob:`*`\ :path:`/`,
-      that portion is removed.
-
-    - If the tail-portion of the remaining path matches
-      :path:`/`\ :var:`name`\ :path:`.framework/` or
-      :path:`/`\ :var:`name`\ :path:`.app/Contents/`,
-      that portion is removed.
-
-  - Otherwise:
-
-    - If the tail-portion of the path matches
-      :path:`/cps/`\ :var:`name-like`\ :path:`/` or
-      :path:`/cps/`,
-      that portion is removed.
-
-    - If the tail-portion of the remaining path matches any of
-      :path:`/`\ :var:`libdir`\ :path:`/` or :path:`/share/`,
-      that portion is removed.
+Various attributes may specify relative paths
+by use of the ``@prefix@`` placeholder.
+In order to resolve these paths,
+it is necessary to know the package's prefix
+(which may or may not be the same
+as :var:`prefix`, above).
+This is accomplished in one of two ways:
+
+- If a package specifies `prefix`_, that value is used.
+
+- If a package specifies `cps_path`_,
+  the prefix shall be determined from that value
+  in combination with the absolute location of the ``.cps`` file.
+
+A correctly specified `cps_path`_ will match the location
+(that is, the path without the final ``.cps`` file name)
+of the ``.cps`` file.
+For example, ``/usr/local/lib/cps/foo/foo.cps``
+specifies ``"cps_path": "@prefix@/lib/cps/foo"``.
+The absolute location is ``/usr/local/lib/cps/foo``
+and the prefix-relative location is ``lib/cps/foo``,
+which matches the trailing portion of the absolute location.
+Therefore, the prefix is the unmatched portion
+of the absolute location, or ``/usr/local``.
+
+If ``fullpath`` is the location of the ``.cps`` file,
+tools shall attempt prefix resolution
+against ``dirname(fullpath)``, at minimum.
+It is recommended that, if this fails,
+tools also attempt prefix resolution
+against ``realpath(dirname(fullpath))``
+and ``dirname(realpath(fullpath))``,
+where ``realpath(...)`` represents the canonicalized
+(that is, with all symlinks fully expanded)
+form of its argument.
 
 .. ... .. ... .. ... .. ... .. ... .. ... .. ... .. ... .. ... .. ... .. ... ..