/build/doc/manual-full.xml:12764:35: error: ID "build-phase" has already been defined
/build/doc/manual-full.xml:9029:33: error: first occurrence of ID "build-phase"
Based on some feedback in #87094 and discussion with @fridh, this re-organizes
the onboarding tutorial in the Nixpkgs manual's python section, so that we start
with the simplest, most ad-hoc examples and work our way up. This progresses
from:
1. How to create an temporary python env at the cmdline, then
2. How to create a specific python env for a single script, then
3. How to create a specific python env for a project in a shell.nix, then
4. How to install a specific python env globally on the system or in a user profile.
Additionally, I've tried to standardize on some of the "best practice" ways of
doing things:
1. Instead of saying that this command style is "supported but strongly not
discouraged", I've just deleted it to avoid confusion.
Bad: nix-shell -p python38Packages.numpy python38Packages.toolz
Good: nix-shell -p 'python38.withPackages(ps: with ps; [ numpy toolz ])'
2. In the portion where we show how to add stuff to the user's
`XDG_CONFIG_HOME`, use overlays instead of `config.nix`. The former can do
everything the latter can do, but is also much more generic and powerful,
because it can compose with other files, compose with other envs, compose
with overlays that do things like swap whether tensorflow and pytorch are
built openblas/mkl/cuda stacks, and so on. The user is eventually going to
see the overlay, so to avoid confusion let's standardize on it.
An overlay by any other name would function just as well, but we generally use
`self: super:` for the regular overlays, and `python-self: python-super`.
Since the introduction of php.unwrapped there's no real need for the
phpXXbase attributes, so let's remove them to lessen potential
confusion and clutter. Also update the docs to make it clear how to
get hold of an unwrapped PHP if needed.
Rework withExtensions / buildEnv to handle currently enabled
extensions better and make them compatible with override. They now
accept a function with the named arguments enabled and all, where
enabled is a list of currently enabled extensions and all is the set
of all extensions. This gives us several nice properties:
- You always get the right version of the list of currently enabled
extensions
- Invocations chain
- It works well with overridden PHP packages - you always get the
correct versions of extensions
As a contrived example of what's possible, you can add ImageMagick,
then override the version and disable fpm, then disable cgi, and
lastly remove the zip extension like this:
{ pkgs ? (import <nixpkgs>) {} }:
with pkgs;
let
phpWithImagick = php74.withExtensions ({ all, enabled }: enabled ++ [ all.imagick ]);
phpWithImagickWithoutFpm743 = phpWithImagick.override {
version = "7.4.3";
sha256 = "wVF7pJV4+y3MZMc6Ptx21PxQfEp6xjmYFYTMfTtMbRQ=";
fpmSupport = false;
};
phpWithImagickWithoutFpmZip743 = phpWithImagickWithoutFpm743.withExtensions (
{ enabled, all }:
lib.filter (e: e != all.zip) enabled);
phpWithImagickWithoutFpmZipCgi743 = phpWithImagickWithoutFpmZip743.override {
cgiSupport = false;
};
in
phpWithImagickWithoutFpmZipCgi743
