Add Platform V1 Spec #1187

rydrman · 2025-03-07T19:21:45Z

The next stage in work for #1121 which adds a new way to specify platforms with static build version as well as separated build and runtime requests.

Here is the updated doc page for reference, note that there is no information about the static build version yet as it's not used by anything:

Specifying Platforms

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 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

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:

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:

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

Signed-off-by: Ryan Bottriell <[email protected]>

This allows for reusing it in the future v1/platform-style requirements Signed-off-by: Ryan Bottriell <[email protected]>

Signed-off-by: Ryan Bottriell <[email protected]>

rydrman · 2025-03-12T21:11:28Z

From the meeting today:

reference docs for v0 platform and v1 platform (like we do for spec)

jrray · 2025-03-18T18:45:04Z

docs/use/platforms.md

+
+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.


Suggested change

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.

As an example, the [VFX Reference Platform](https://vfxplatform.com/) provides "a set of tools and library versions 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 kinds of recommendations.

jrray · 2025-03-18T18:45:53Z

docs/use/platforms.md

+
+### 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.


Suggested change

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.

At their core, platforms are a convenient way to write package specs that only provide an opinion on what versions can be used and nothing else. Once defined, platforms are still built, published, and used the same way as any other package.

jrray · 2025-03-18T18:46:38Z

docs/use/platforms.md

+    atRuntime: 3
+```
+
+The `platform:` fields provides the name of the platform package. The


Suggested change

The `platform:` fields provides the name of the platform package. The

The `platform:` field provides the name of the platform package. The

jrray · 2025-03-18T18:48:44Z

docs/use/platforms.md

+
+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.


Suggested change

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.

By inheriting from base packages, platforms can augment and override their requirements. For example, a DCC (Digital Content Creation) application platform can inherit the requirements from company or site-specific platforms and then introduce additional constraints for the application itself.

jrray · 2025-03-18T18:49:25Z

docs/use/platforms.md

+  - pkg: python
+    atBuild: =3.7.10
+    atRuntime: 3.7
+  # it also has no need to constrain the version of imath that's used


Suggested change

# it also has no need to constrain the version of imath that's used

# it also has no need to constrain the version of imath that is used

jrray · 2025-03-18T19:13:44Z

crates/spk-schema/crates/ident/src/request.rs

+    /// Return the canonical name of this request.
+    pub fn name(&self) -> &OptName {
+        spk_schema_foundation::spec_ops::Named::name(self)
+    }


Is there a reason to keep this?

jrray · 2025-03-18T20:56:26Z

crates/spk-schema/src/component_spec_list.rs

+        self.iter().find(|c| name == c.name)
+    }
+
+    /// Retrieve a component with the provided name or build an insert new one


Suggested change

/// Retrieve a component with the provided name or build an insert new one

/// Retrieve a component with the provided name or insert a new one

jrray · 2025-03-18T21:08:20Z

crates/spk-schema/src/requirements_list.rs

+    }
+
+    /// Get a mutable reference to the first request with the given name
+    pub fn get_mut(&mut self, name: impl AsRef<str>) -> Option<&mut R> {


This allows the caller to violate the unique name invariant by changing the name of item returned.

jrray · 2025-03-18T21:26:54Z

crates/spk-schema/src/requirements_list.rs

+    /// All requests with the same name as the given name are removed
+    /// from the list.


No arguments about the implementation here but there is an invariant that names can't be repeated, so the way this is worded is a bit misleading since it implies it could be normal for there to be multiples.

I recognize that this is an existing docstring that is just being relocated.

jrray · 2025-03-18T21:52:12Z

crates/spk-schema/src/v1/platform_test.rs

+           - pkg: inherit-me2
+             atRuntime: false


- pkg: inherit-me2 atBuild: =1.0.0 atRuntime: false

What would happen if I wrote this?

Will it be legal to say a package is required [to be a specific version] for build environments but have no influence on runtime environments?

I'm not necessarily arguing for that to be a feature, but looking at this test behavior it is treating this as deleting inherit-me2 from the list. Would the same happen if this said atBuild: false instead of atRuntime: false?

If it is not possible to mix and match false and not-false then I would suggest a different way of expressing deletes, like we have in v0.

rydrman added 6 commits March 7, 2025 08:07

Add AsRef<str> impl for unowned parsedbuf

8243114

Signed-off-by: Ryan Bottriell <[email protected]>

Allow Named trait to be used for types that have an OptName

b53a101

Signed-off-by: Ryan Bottriell <[email protected]>

Expand RequirementsList and make it generic over some named type

18cc3f4

This allows for reusing it in the future v1/platform-style requirements Signed-off-by: Ryan Bottriell <[email protected]>

Allow unit value to be used as empty build env

10c867c

Signed-off-by: Ryan Bottriell <[email protected]>

Support ser/de operations on version filter directly

0e7bb4f

Signed-off-by: Ryan Bottriell <[email protected]>

Add convenience methods for named components in component spec list

f8353dd

Signed-off-by: Ryan Bottriell <[email protected]>

rydrman added the enhancement New feature or request label Mar 7, 2025

rydrman requested review from jrray and dcookspi March 7, 2025 19:21

rydrman self-assigned this Mar 7, 2025

rydrman force-pushed the workspaces3 branch 2 times, most recently from b24fa83 to 6d9277b Compare March 7, 2025 19:28

rydrman added 4 commits March 7, 2025 12:07

Add an initial implementation of the v1 platform spec

9ad0e86

Signed-off-by: Ryan Bottriell <[email protected]>

Allow v1 platform to be parsed as a recipe spec

d109b39

Signed-off-by: Ryan Bottriell <[email protected]>

Remove unnecessary to_owned

73f6942

Signed-off-by: Ryan Bottriell <[email protected]>

Split the docs on platform into their own page

10cabc1

Signed-off-by: Ryan Bottriell <[email protected]>

rydrman force-pushed the workspaces3 branch from 6d9277b to 10cabc1 Compare March 7, 2025 20:07

Base automatically changed from rust-edition-2024 to main March 8, 2025 01:59

jrray requested changes Mar 18, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add Platform V1 Spec #1187

Add Platform V1 Spec #1187

rydrman commented Mar 7, 2025

rydrman commented Mar 12, 2025

jrray Mar 18, 2025

jrray Mar 18, 2025

jrray Mar 18, 2025

jrray Mar 18, 2025

jrray Mar 18, 2025

jrray Mar 18, 2025

jrray Mar 18, 2025

jrray Mar 18, 2025

jrray Mar 18, 2025

jrray Mar 18, 2025


		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.

	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.
	At their core, platforms are a convenient way to write package specs that only provide an opinion on what versions can be used and nothing else. Once defined, platforms are still built, published, and used the same way as any other package.

	The `platform:` fields provides the name of the platform package. The
	The `platform:` field provides the name of the platform package. The

	# it also has no need to constrain the version of imath that's used
	# it also has no need to constrain the version of imath that is used

	/// Retrieve a component with the provided name or build an insert new one
	/// Retrieve a component with the provided name or insert a new one

		/// All requests with the same name as the given name are removed
		/// from the list.

Add Platform V1 Spec #1187

Are you sure you want to change the base?

Add Platform V1 Spec #1187

Conversation

rydrman commented Mar 7, 2025

Specifying Platforms

Platforms are Packages

Creating Platforms

Inheritance

rydrman commented Mar 12, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment