nixpkgs/pkgs/stdenv/darwin/README.md

# Darwin stdenv design goals

There are two more goals worth calling out explicitly:

1. The standard environment should build successfully with sandboxing enabled on Darwin. It is
   fine if a package requires a `sandboxProfile` to build, but it should not be necessary to
   disable the sandbox to build the stdenv successfully; and
2. The output should depend weakly on the bootstrap tools. Historically, Darwin required updating
   the bootstrap tools prior to updating the version of LLVM used in the standard environment.
   By not depending on a specific version, the LLVM used on Darwin can be updated simply by
   bumping the definition of llvmPackages in `all-packages.nix`.

# Updating the stdenv

There are effectively two steps when updating the standard environment:

1. Update the definition of llvmPackages in `all-packages.nix` for Darwin to match the value of
   llvmPackages.latest in `all-packages.nix`. Timing-wise, this done currently using the spring
   release of LLVM and once llvmPackages.latest has been updated to match. If the LLVM project
   has announced a release schedule of patch updates, wait until those are in nixpkgs. Otherwise,
   the LLVM updates will have to go through staging instead of being merged into master; and
2. Fix the resulting breakage. Most things break due to additional warnings being turned into
   errors or additional strictness applied by LLVM. Fixes may come in the form of disabling those
   new warnings or by fixing the actual source (e.g., with a patch or update upstream). If the
   fix is trivial (e.g., adding a missing int to an implicit declaration), it is better to fix
   the problem instead of silencing the warning.
darwin.stdenv: refactor stdenv definition In preparation for bumping the LLVM used by Darwin, this change refactors and reworks the stdenv build process. When it made sense, existing behaviors were kept to avoid causing any unwanted breakage. However, there are some differences. The reasoning and differences are discussed below. - Improved cycle times - Working on the Darwin stdenv was a tedious process because `allowedRequisites` determined what was allowed between stages. If you made a mistake, you might have to wait a considerable amount of time for the build to fail. Using assertions makes many errors fail at evaluation time and makes moving things around safer and easier to do. - Decoupling from bootstrap tools - The stdenv build process builds as much as it can in the early stages to remove the requirement that the bootstrap tools need bumped in order to bump the stdenv itself. This should lower the barrier to updates and make it easier to bump in the future. It also allows changes to be made without requiring additional tools be added to the bootstrap tools. - Patterned after the Linux stdenv - I tried to follow the patterns established in the Linux stdenv with adaptations made to Darwin’s needs. My hope is this makes the Darwin stdenv more approable for non-Darwin developers who made need to interact with it. It also allowed some of the hacks to be removed. - Documentation - Comments were added explaining what was happening and why things were being done. This is particular important for some stages that might not be obvious (such as the sysctl stage). - Cleanup - Converting the intermediate `allowedRequisites` to assertions revealed that many packages were being referenced that no longer exist or have been renamed. Removing them reduces clutter and should help make the stdenv bootstrap process be more understandable. 2023-05-10 07:03:00 +00:00			`# Darwin stdenv design goals`

			`There are two more goals worth calling out explicitly:`

			`1. The standard environment should build successfully with sandboxing enabled on Darwin. It is`
			fine if a package requires a `sandboxProfile` to build, but it should not be necessary to
			`disable the sandbox to build the stdenv successfully; and`
			`2. The output should depend weakly on the bootstrap tools. Historically, Darwin required updating`
			`the bootstrap tools prior to updating the version of LLVM used in the standard environment.`
			`By not depending on a specific version, the LLVM used on Darwin can be updated simply by`
			bumping the definition of llvmPackages in `all-packages.nix`.

			`# Updating the stdenv`

			`There are effectively two steps when updating the standard environment:`

			1. Update the definition of llvmPackages in `all-packages.nix` for Darwin to match the value of
			llvmPackages.latest in `all-packages.nix`. Timing-wise, this done currently using the spring
			`release of LLVM and once llvmPackages.latest has been updated to match. If the LLVM project`
			`has announced a release schedule of patch updates, wait until those are in nixpkgs. Otherwise,`
			`the LLVM updates will have to go through staging instead of being merged into master; and`
			`2. Fix the resulting breakage. Most things break due to additional warnings being turned into`
			`errors or additional strictness applied by LLVM. Fixes may come in the form of disabling those`
			`new warnings or by fixing the actual source (e.g., with a patch or update upstream). If the`
			`fix is trivial (e.g., adding a missing int to an implicit declaration), it is better to fix`
			`the problem instead of silencing the warning.`