Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: Document Platform Support Tiers #245368

Closed
wants to merge 3 commits into from
Closed

doc: Document Platform Support Tiers #245368

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9a6837d
doc: Document Platform Support Tiers
asymmetric Jul 25, 2023
9255f0c
add more TODOs
asymmetric Jul 25, 2023
83db0cf
Apply suggestions from @amjoseph-nixpkgs
asymmetric Aug 1, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions doc/manual.md.in
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,3 +12,8 @@ stdenv.md
builders.md
contributing.md
```

```{=include=} appendix
stdenv/platform-support-tiers.chapter.md
```

88 changes: 88 additions & 0 deletions doc/stdenv/platform-support-tiers.chapter.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,88 @@
# Platform Support Tiers {#platform-support-tiers}
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
# Platform Support Tiers {#platform-support-tiers}
# Non-normative Platform Support Tiers {#platform-support-tiers}

The RFC specifies these as "non-normative" (and also nearly four years out of date at this point).


In the context of Nixpkgs, a *platform* means an attrset which typechecks against `lib.systems.parsed.types.parsedPlatform`. This includes a CPU architecture, bitwidth, and endianness and may also include: an OS kernel, environment (also called "C library"), choice of compiler and linker, option to link statically, and other data.

Nixpkgs defines 7 platform *support tiers*, meaning levels of support for each platform.

- **TODO**: change "build successfully" to a definition of "work" that includes tests?
- **TODO**: mention binary cache?

## Tier 1 {#platform-support-tier-1}

These platforms receive the highest level of support, meaning that every
platform-compatible package in Nixpkgs must successfully build in the Hydra and OfBorg CIs.
**TODO**: this seems to not be entirely true for Hydra, but true for OfBorg.

- `x86_64-linux-gnu` using `gcc`

## Tier 2 {#platform-support-tier-2}

Many of the packages are required to build successfully on these platforms in CI, the rest are supported on a best-effort basis by dedicated platform maintainers.
**TODO**: link teams
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Problem is that the @NixOS/aarch64-maintainers mandated by the RFC was never created

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See NixOS/rfcs#46 (comment)


- `aarch64-linux`, `gcc+glibc`
- `x86_64-darwin`, `clang+Darwin/macOS`

## Tier 3 {#platform-support-tier-3}

None of the packages for these platforms are required to build successfully in
CI, but it is expected that most of them will build successfully.

- `i686-linux-gnu`, `gcc`
- `armv{6,7,8}*-linux-gnu`, `gcc`
- `armv{6,7,8}*-linux-gnu`, `gcc`, cross-compilation
- `aarch64-linux-gnu`, `gcc`, cross-compilation
- `mipsel-linux-gnu`, `gcc`
- `x86_64-linux-musl`, `gcc`

## Tier 4 {#platform-support-tier-4}

Some of the packages for these platforms are expected to work. The
[`exotic-platform-maintainers`
Team](https://github.com/orgs/NixOS/teams/exotic-platform-maintainers) is
responsible for this platform.

- `aarch64-none`
- `avr`
- `arm-none`
- `i686-none`
- `x86_64-none`
- `powerpc-none`
- `powerpcle-none`
- `powerpc64le-linux-gnu`
- `mips64el-linux-gnuabi64`
- `x86_64-mingw32`
- `i686-mingw32`
- `x86_64-linux-musl`, `gcc` — static
- `x86_64-linux-gnu`, `clang`
- `x86_64-linux-gnu`, `clang` — `llvm` linker
- `x86_64-linux-android`
- `aarch64-linux-android`
- `armv{7,8}-linux-android`

## Tier 5 {#platform-support-tier-5}

A small number of packages might build successfully on these platforms.

- `x86_64-linux`, `gcc`+`glibc` — static
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure this is correct. I don't think static linking is truly possible with glibc.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@7c6f434c what do you say?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We do have something that claims to be static linking with glibc. I am not sure which of the, say, NSS things it ends up doing with dynamic linking, but it does seem to link statically some stuff? As there are packages that depend on glibc.static, I tried to describe this build configuration as a platform…

- `x86_64-linux-gnu`, `gcc` `llvm` linker

## Tier 6 {#platform-support-tier-6}

These platforms are defined in Nixpkgs, but no packages are expected to build on them.

- `wasm-wasi`

## Tier 7 {#platform-support-tier-7}

No current support, but previous support or clear path to add support.

- `aarch64-darwin`
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This seems to be false now, since OfBorg builds for this platform.

Copy link
Member

@7c6f434c 7c6f434c Jul 25, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, it looks like right now after all the work done, two macOS versions are mostly on par (although capacity issues at ofBorg make it questionable if aarch64-linux has tooling of «a bit better than T3» but not really «almost T2»). And upstream pretends that the latter is the continuation of the former in some sense.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm inclined towards leaving this at the state it was when the RFC was accepted, since I don't have the resources to update the list on my own.

The RFC also requires documentation be kept up to date, so that could be the next step (and the task of the respective arch maintainers) once this is merged.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm inclined towards leaving this at the state it was when the RFC was accepted, since I don't have the resources to update the list on my own.

In that case you should probably close this PR.

Adding inaccurate data to the documentation is not helpful.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well, it's inaccurate until someone fixes it, and seeing how nothing has happened in 3 years, this PR might at least get some things moving.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But let's see if we gather more up to date info with this PR. Thank you for your contributions to that end.

- `i686-darwin`
- `x86_64-freebsd`
- `i686-solaris`
- `x86_64-illumos`

## Further reading {#platform-support-tiers-further-reading}

For a formal definition of platform support tiers, see [RFC046](https://github.com/7c6f434c/rfcs/blob/platform-support-tiers/rfcs/0046-platform-support-tiers.md).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it is better to include the definition in the manual: then small technical cleanups of the description can be made on the basis of technical review + not changing the intent of RFC.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What definition would you add here then?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would stupidly add lines 55 to 275 from the RFC. This definitely covers «definition of support tiers» (and at least a half of it is definitely necessary). If this PR is «copy what RFC calls to copy» and updates (including formatting) are the next step, I think this is a reasonable way to handle definitions.