Split the docs on platform into their own page

rydrman · rydrman · commit 10cabc1bbb42 · 2025-03-07T12:07:52.000-08:00
Signed-off-by: Ryan Bottriell &lt;rbottriell@ilm.com&gt;
diff --git a/docs/ref/spec.md b/docs/ref/spec.md
@@ -27,7 +27,7 @@ The root package spec defines which fields can and should exist at the top level
 | ----------- | -------------- | ---------------------------------------------------------------------- |
 | description | _str_          | (Optional) A concise, one sentence description of the package          |
 | homepage    | _str_          | (Optional) URL where the package lives                                 |
-| license     | _str_          | (Optional) Package license. If not specified, defaults to _Unlicensed_ |
+| license     | _str_          | (Optional) Package license. If not specified, defaults to _Unlicensed_ |
 | labels      | _Map[str,str]_ | (Optional) A storage for arbitrary key-value data                      |
 
 ## SourceSpec
diff --git a/docs/use/platforms.md b/docs/use/platforms.md
@@ -0,0 +1,93 @@
+---
+title: Specifying Platforms
+summary: Platforms constrain environments to help development teams stay consistent.
+weight: 25
+---
+
+As a concept, platforms are packages that only provide _opinions_ on what should exist in an environment. They contain no files or code, and have no concrete dependencies but limit what versions are allowed in order to enforce consistency across teams, applications and developers.
+
+As an example, the [VFX Reference Platform](https://vfxplatform.com/) provides "a set of tools and library version to be used as a common target platform for building software for the VFX industry". Platforms in SPK were designed to be able to describe and enforce these kind of recommendations.
+
+### Platforms are Packages
+
+At their core, platforms are a convent way to write package specs that only provide an opinion on what versions can be used and nothing else. Once defines, platforms are still built, published, and used the same way as any other package.
+
+A platform spec reduces the amount of boilerplate needed to set up a platform package compared to using the full `v0/package` recipe format. A platform spec will be filled in with appropriate defaults automatically for a platform-style package.
+
+### Creating Platforms
+
+Below is an example platform
+
+```yaml
+api: v1/platform
+platform: company-platform/2025.01.01
+requirements:
+  - pkg: gcc
+    atBuild: =9.3.1
+    atRuntime: 9.3.1
+  - pkg: python
+    atBuild: =3.9.18
+    atRuntime: 3.9
+  - pkg: imath
+    atBuild: =3.0.1
+    atRuntime: 3
+```
+
+The `platform:` fields provides the name of the platform package. The
+`api:` field indicates this is a platform spec.
+
+The `requirements` field contains the list of requirements in the
+platform. In each case, the requirement specifies the version request to be
+used at build time vs at run time. This allows the platform to differently
+constrain the requirement depending on if it's being used to define a build
+environment or a runtime environment.
+
+These requirements are placed onto the `build` and `run` components of the package
+generated by this platform, respectively. The generated requirements will have
+`include: IfAlreadyPresent` added to them automatically, it does not need to be
+specified for them.
+
+#### Inheritance
+
+Additionally, the platform spec provides a way to inherit requirements from another package. Typically, it makes the most sense to inherit from another platform, but it could be any package.
+
+By inheriting from base packages, platforms can augment and override their requirements. For example, a DCC (Digital Concent Creation) application platform can inherit the requirements from company or site-specific platform and then introduce additional constraints for the application itself.
+
+Here is an example platform spec that inherits from the 'company-platform' and makes adjustments of its own:
+
+```yaml
+api: v1/platform
+platform: dcc-platform/2025.01.01
+base:
+  - company-platform/2024.01.01
+requirements:
+  # this DCC uses an older version of python
+  - pkg: python
+    atBuild: =3.7.10
+    atRuntime: 3.7
+  # it also has no need to constrain the version of imath that's used
+  - pkg: imath
+    atBuild: false
+    atRuntime: false
+```
+
+The `base:` field indicates which platform this one inherits from. In the case of multiple bases, each one simply overrides the previous in turn.
+
+Any `atBuild` or `atRuntime` value that is specified in the platform spec will override the same value for the named requirement in the bases. Conversely, this also means that if a requirement omits either of the `atBuild` or `atRuntime` fields, then the value from the base will still remain.
+
+The special `false` value can be used to remove the requirement entirely.
+
+This is the complete specification of the same resulting `dcc-platform` without basing it on the `company-platform`:
+
+```yaml
+api: v1/platform
+platform: dcc-platform
+requirements:
+  - pkg: gcc
+    atBuild: =9.3.1
+    atRuntime: 9.3.1
+  - pkg: python
+    atBuild: =3.7.10
+    atRuntime: 3.7
+  # - pkg: imath not present
+```
diff --git a/docs/use/spec.md b/docs/use/spec.md
@@ -203,7 +203,7 @@ build:
 
 The build script is bash code which builds your package. The script is responsible for installing your software into the `/spfs` directory.
 
-spk assumes that your installed files will be layed out similarly to the unix standard filesystem hierarchy. Most build systems can be configured with a **prefix**-type argument like the cmake example above which will handle this for you. If you are create python code, spk works just like an python virtual environment, and your code can be pip-installed using the /spfs/bin/pip that is included in the spk python packages or by manually copying to the appropriate `/spfs/lib/python<version>/site-packages` folder.
+spk assumes that your installed files will be laid out similarly to the unix standard filesystem hierarchy. Most build systems can be configured with a **prefix**-type argument like the cmake example above which will handle this for you. If you are create python code, spk works just like an python virtual environment, and your code can be pip-installed using the /spfs/bin/pip that is included in the spk python packages or by manually copying to the appropriate `/spfs/lib/python<version>/site-packages` folder.
 
 {{% notice tip %}}
 If your build script is getting long or feels obstructive in your spec file, you can also create a build.sh script in your source tree which will be run if no build script is specified.
@@ -257,6 +257,10 @@ The spk build system performs a number of validations against the package create
 
 The install configuration specifies the environment that your package needs when it is installed or included in an spk environment.
 
+{{% notice info %}}
+Packages that only provide opinions/constraints on an environment, but no actual dependencies or content are considered 'platform' packages. SPK provides a native spec for this use case, see {{< ref "./platforms" >}}.
+{{% /notice %}}
+
 #### Environment Variables
 
 Packages can append, prepend and set environment variables at runtime if needed. Furthermore, you are able to add comments and set the priority of the generated activation script. It's strongly encouraged to only modify variables that your package can reasonably take ownership for. For example, the `python` package should be the only one setting `PYTHON*` variables that affect the runtime of python. This is not an enforced rule, but if you find yourself setting `PYTHONPATH`, for example, then it might mean that you are installing to a non-standard location within spfs and breaking away from the intended consistency of spfs.
@@ -414,105 +418,6 @@ install:
           - { var: abi, static: cp27m }
 ```
 
-#### Platform Package Specs
-
-Platforms are a convenience for writing the package spec for
-"meta-packages" used to specify versions of a set of packages. They
-are used to constrain builds of other packages and do not contain
-usable programs, libraries or code themselves.
-
-A typical platform package has an empty build options list, and one or
-more install requirements, all in `IfAlreadyPresent` mode. These
-install requirements describe the versions of dependencies that target
-compatibility with some application execution environment, like a
-DCC.
-
-A platform spec reduces the amount of boilerplate needed to set up a
-platform package compared to using the v0/package recipe format. A
-platform spec will be filled in with appropriate defaults
-automatically for a platform.
-
-The platform spec also provides a way to inherit package requirements
-from another package, such as another platform. This allows platforms
-to be based on other platforms without respecifying the same
-requirements, e.g. a DCC specific platform can pull in the
-requirements in a company or site specific platform. The expectation
-is that a platform would only inherit from other platforms, but that
-is not strictly required.
-
-When a platform is built, it produces an ordinary v0/package just like
-a "normal" v0/package spec would do, and it is treated like any other
-package for use by downstream consumers. All its requirements will
-always be `IfAlreadyPresent` ones.
-
-An example platform spec:
-
-```yaml
-platform: company-platform
-api: v1/platform
-requirements:
-  - pkg: gcc
-    atBuild: =9.3.1
-    atRuntime: 9.3.1
-  - pkg: python
-    atBuild: =3.9.18
-    atRuntime: 3.9
-  - pkg: imath
-    atBuild: =3.0.1
-    atRuntime: 3
-```
-
-The `platform:` fields provides the name of the platform package. The
-`api:` field indicates this is a platform spec.
-
-The `requirements` field contains the list of requirements in the
-platform. In each case, the requirement specifies the version request to be
-used at build time vs at run time. This allows the platform to differently
-constrain the requirement depending on if it's being used to define a build
-environment or a runtime environment.
-
-These requirements are placed onto the `build` and `run` components of the package
-generated by this platform, respectively. The generated requirements will have
-`include: IfAlreadyPresent` added to them automatically, it does not need to be
-specified for them.
-
-An example platform spec that inherits from the 'company-platform' and makes adjustments of its own:
-
-```yaml
-platform: dcc-platform
-base:
-  - company-platform
-api: v0/platform
-requirements:
-  - pkg: python
-    atBuild: =3.7.10
-    atRuntime: 3.7
-  - pkg: imath
-    atBuild: false
-    atRuntime: false
-```
-
-The `base:` field indicates which platform this platform spec is based on (inherits the requirements from). In the case of multiple bases, each one simply overrides the previous in turn.
-
-Any `atBuild` or `atRuntime` value that is specified in the platform spec will override the same value for the named requirement in the bases. Conversely, this also means that if a requirement omits either of the `atBuild` or `atRuntime` fields, then the value from the base will still remain.
-
-The special `false` value can be used to remove the requirement entirely.
-
-This is the complete specification of the same resulting `dcc-platform` without basing it on the `company-platform`:
-
-```yaml
-platform: dcc-platform
-api: v0/platform
-requirements:
-  - pkg: gcc
-    atBuild: =9.3.1
-    atRuntime: 9.3.1
-  - pkg: python
-    atBuild: =3.7.10
-    atRuntime: 3.7
-  # - pkg: imath not present
-```
-
 ### Testing
 
 Tests can also be defined in the package spec file. SPK currently supports three types of tests that validate different aspects of the package. Tests are defined by a bash script and _stage_.
